<!DOCTYPE html>
<!--
     SPDX-License-Identifier: CC-BY-SA-4.0
     SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
-->
<!-- Page last generated 2025-02-20 03:16:15 +0000 -->
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Introduction to CAmkES | seL4 docs</title>

    <!-- Our stylesheet and theme stylesheet.  Contains bootstrap. -->
    <link rel="stylesheet" href="/assets/css/style.css" type="text/css">
    <!-- Font awesome -->
    <link href="https://use.fontawesome.com/releases/v5.0.8/css/all.css" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
    <!-- Pygments syntax highlighting  -->
    <link rel="stylesheet" href="/assets/css/highlighting/trac.css" type="text/css">
    <link rel="icon" type="image/x-icon" href="/assets/favicon.ico"><script defer data-domain="docs.sel4.systems"
	    src="https://analytics.sel4.systems/js/script.js"></script></head>

  <body class="container-fluid">

    



<header>
  <ul class="row menu">
    <li class="col-xs-12 col-md-2" >
            <a href="https://sel4.systems" class="skip-icon">
              <img class="img-responsive" src="/assets/logo-text-white.svg" alt="seL4 logo" />
            </a>
    </li>
    <li class="col-xs-12 col-md-10 menu">
      <nav aria-label="Banner links">
        <h2><a href="/Resources" />Resources</h2>
        <h2><a href="/processes" />Contributing</a></h2>
        <h2><a href="/projects" />Projects</h2>
        <h2><a href="/Tutorials" />Tutorials</h2>
        <iframe title="DuckDuckGo search bar" src="https://duckduckgo.com/search.html?site=docs.sel4.systems&prefill=Search%20sel4.systems" style="overflow:hidden;margin-bottom:10px; padding:0;height:40px;float:right;border-width: 0px"></iframe>
      </nav>
    </li>
  </ul>
  <div class="clear"></div>
  
<div class="breadcrumbs bootstrap hidden-sm-down">
  <nav class="sel-breadcrumb" aria-label="Breadcrumb" >
    <ol class=" list-unstyled" vocab="http://schema.org/" typeof="BreadcrumbList">
      
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/">
              <span property="name"><b>seL4 Docs</b></span>
            </a>
            <meta property="position" content="1" />
        </li>
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/Tutorials/">
              <span property="name"><b>Tutorials</b></span>
            </a>
            <meta property="position" content="2" />
        </li>
      
        

        
          <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <span property="name">Introduction to CAmkES</span>
            <meta property="position" content="3" /></li>
          
    </ol>
  </nav>
  <nav class="sel-version" aria-label="Current Versions">
    <ol class="list-unstyled">
      <li class="list-unstyled text-right" style="margin-left:auto; padding:0rem 0rem;">
        Current versions:</li>
      <li class="list-unstyled text-right">
      <a href="/releases/sel4/13.0.0"><b>seL4-13.0.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/microkit/1.4.1"><b>microkit-1.4.1</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/camkes/camkes-3.11.0"><b>camkes-3.11.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/capdl/0.3.0"><b>capDL-0.3.0</b></a></li>
      </ol>
  </nav>
  <div class='clear'></div>
</div>


</header>

    <main>
      <div class="row">
  <div class="hidden-xs col-sm-4 col-md-3 col-lg-2">
    

<div class="sidebar">
  <ul class="nav nav-sidebar tutorial-sidebar">
    <li class="nav-section">Getting started</li>
      <li><a href="/Tutorials/">Overview</a></li>
      <li><a href="/Tutorials/pathways">Tutorial pathways</a></li>
    <li class="nav-section">seL4</li>
      <li><a href="/Tutorials/setting-up">Setting up your machine</a></li>
      <li><a href="/Tutorials/get-the-tutorials">Getting the tutorials</a></li>
      <li><a href="/Tutorials/hello-world">Hello world</a></li>
      <li><a href="/Tutorials/capabilities">Capabilities</a></li>
      <li><a href="/Tutorials/untyped">Untyped</a></li>
      <li><a href="/Tutorials/mapping">Mapping</a></li>
      <li><a href="/Tutorials/threads">Threads</a></li>
      <li><a href="/Tutorials/ipc">IPC</a></li>
      <li><a href="/Tutorials/notifications">Notifications</a></li>
      <li><a href="/Tutorials/interrupts">Interrupts</a></li>
      <li><a href="/Tutorials/fault-handlers">Fault handling</a></li>
      <li><a href="/Tutorials/mcs">MCS extensions</a></li>
    <li class="nav-section">C Libraries</li>
      <li><a href="/Tutorials/libraries-1">Initialisation &amp; threading</a></li>
      <li><a href="/Tutorials/libraries-2">IPC</a></li>
      <li><a href="/Tutorials/libraries-3">Processes &amp; Elf loading</a></li>
      <li><a href="/Tutorials/libraries-4">Timer</a></li>
    <li class="nav-section">Microkit</li>
      <li><a href="https://trustworthy.systems/projects/microkit/tutorial/">Tutorial</a></li>
    <li class="nav-section">CAmkES</li>
      <li><a href="/Tutorials/hello-camkes-0">Hello CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-1">Introduction to CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-2">Events in CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-timer">CAmkES timer tutorial</a></li>
      <li><a href="/Tutorials/camkes-vm-linux">CAmkES VM</a></li>
      <li><a href="/Tutorials/camkes-vm-crossvm">CAmkES cross-VM connectors</a></li>
    <li class="nav-section">Rust</li>
      <li><a href="https://github.com/seL4/rust-sel4">GitHub</a></li>
    <li class="nav-section">Resources</li>
      <li><a href="https://sel4.systems/Info/Docs/seL4-manual-latest.pdf">seL4 Manual</a></li>
      <li><a href="/projects/sel4/api-doc.html">seL4 API reference</a></li>
      <li><a href="/Tutorials/how-to">How to: a quick solutions guide</a></li>
      <li><a href="/projects/sel4-tutorials/debugging-guide">Debugging guide</a></li>
      <li><a href="/Resources#contact">Help contacts</a></li>
  </ul>
</div>

  </div>
  <div class="content col-sm-8 col-md-6 col-lg-7 main">

    
<!--
  Copyright 2017, Data61, CSIRO (ABN 41 687 119 230)

  SPDX-License-Identifier: BSD-2-Clause
-->

<h1 id="introduction-to-camkes">Introduction to CAmkES</h1>

<p>This tutorial is an introduction to
CAmkES: bootstrapping a basic static CAmkES application, describing its
components, and linking them together.</p>

<p>Outcomes:</p>
<ol>
  <li>Understand the structure of a CAmkES application, as a described,
well-defined, static system.</li>
  <li>Understand the file-layout of a CAmkES ADL project.</li>
  <li>Become acquainted with the basics of creating a practical CAmkES application.</li>
</ol>

<p>Use this <a href="https://github.com/seL4/sel4-tutorials/blob/master/docs/CAmkESTutorial.pdf">slide presentation</a> to guide you through the tutorials <a href="/Tutorials/hello-camkes-0">0</a>, <a href="/Tutorials/hello-camkes-1">1</a> and <a href="/Tutorials/hello-camkes-2">2</a>.</p>

<h2 id="prerequisites">Prerequisites</h2>
<ol>
  <li><a href="/Tutorials/setting-up">Set up your machine</a></li>
  <li><a href="/Tutorials/hello-camkes-0">CAmkES hello world tutorial</a></li>
</ol>

<h2 id="initialising">Initialising</h2>

<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># For instructions about obtaining the tutorial sources see https://docs.sel4.systems/Tutorials/get-the-tutorials</span>
<span class="c">#</span>
<span class="c"># Follow these instructions to initialise the tutorial</span>
<span class="c"># initialising the build directory with a tutorial exercise</span>
./init <span class="nt">--tut</span> hello-camkes-1
<span class="c"># building the tutorial exercise</span>
<span class="nb">cd </span>hello-camkes-1_build
ninja
</code></pre></div></div>

<details>
  <summary><em>Hint:</em> tutorial solutions</summary>
  <p><br />
All tutorials come with complete solutions. To get solutions run:</p>

  <div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># For instructions about obtaining the tutorial sources see https://docs.sel4.systems/Tutorials/get-the-tutorials</span>
<span class="c">#</span>
<span class="c"># Follow these instructions to initialise the tutorial</span>
<span class="c"># initialising the build directory with a tutorial exercise</span>
./init <span class="nt">--solution</span> <span class="nt">--tut</span> hello-camkes-1
<span class="c"># building the tutorial exercise</span>
<span class="nb">cd </span>hello-camkes-1_build
ninja
</code></pre></div>  </div>

</details>

<h2 id="background">Background</h2>

<p>The fundamentals of CAmkES are the component, the interface and the connection.</p>

<h3 id="components">Components</h3>

<p><em>Components</em> are logical
groupings of code and resources. They communicate with other component
instances via well-defined interfaces which must be statically defined,
over communication channels. This tutorial will lead you through the
construction of a CAmkES application with two components: an Echo
server, and its Client that makes calls to it. These components are
defined when you initialise your build repository, found in
the following camkes file:</p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">hello-camkes-1/hello-1.camkes</code></li>
</ul>

<p>Find the Component manual section here:
<a href="https://github.com/seL4/camkes-tool/blob/master/docs/index.md#component">https://github.com/seL4/camkes-tool/blob/master/docs/index.md#component</a></p>

<h3 id="connections">Connections</h3>

<p>The second fundamental component of CAmkES applications
is the <em>Connection</em>: a connection is the representation of a method of
communication between two software components in CAmkES. The underlying
implementation may be shared memory, synchronous IPC, notifications or
some other implementation-provided means. In this particular tutorial,
we are using synchronous IPC. In implementation terms, this boils down
to the <code class="language-plaintext highlighter-rouge">seL4_Call</code> syscall on seL4.</p>

<p>Find the “Connection” keyword manual section here:
<a href="https://github.com/seL4/camkes-tool/blob/master/docs/index.md#connection">https://github.com/seL4/camkes-tool/blob/master/docs/index.md#connection</a></p>

<h3 id="interfaces">Interfaces</h3>

<p>All communications over a CAmkES connection must be well
defined: static systems’ communications should be able to be reasoned
about at build time. All the function calls which will be delivered over
a communication channel then, also are well defined, and logically
grouped so as to provide clear directional understanding of all
transmissions over a connection. Components are connected together in
CAmkES, yes – but the interfaces that are exposed over each connection
for calling by other components, are also described.</p>

<p>There are different
kinds of interfaces:
-Dataports,
-Procedural interfaces,
-and Notifications.</p>

<p>This tutorial will lead you through the construction of a Procedural
interface, which is an interface over which function calls are made
according to a well-defined pre-determined API. The keyword for this
kind of interface in CAmkES is <code class="language-plaintext highlighter-rouge">procedure</code>. The definition of this
Procedure interface may be found here:
<code class="language-plaintext highlighter-rouge">hello-camkes-1/interfaces/HelloSimple.idl4</code></p>

<p>Find the “Procedure” keyword definition here:
<a href="https://github.com/seL4/camkes-tool/blob/master/docs/index.md#procedure">https://github.com/seL4/camkes-tool/blob/master/docs/index.md#procedure</a></p>

<h3 id="component-source">Component source</h3>

<p>Based on the ADL, CAmkES generates boilerplate which
conforms to your system’s architecture, and enables you to fill in the
spaces with your program’s logic. The two generated files in this
tutorial application are, in accordance with the Components we have
defined:</p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">hello-camkes-1/components/Echo/src/echo.c</code></li>
  <li><code class="language-plaintext highlighter-rouge">hello-camkes-1/components/Client/src/client.c</code></li>
</ul>

<p>Now when it comes to invoking the functions that were defined in the
Interface specification
(<code class="language-plaintext highlighter-rouge">hello-camkes-1/interfaces/HelloSimple.idl4</code>),
you must prefix the API function name with the name of the Interface
instance that you are exposing over the particular connection.</p>

<p>The reason for this is because it is possible for one component to
expose an interface multiple times, with each instance of that interface
referring to a different function altogether. For example, if a
composite device, such as a network card with with a serial interface
integrated into it, exposes two instances of a procedural interface that
has a particular procedure named <code class="language-plaintext highlighter-rouge">send()</code> – how will the caller of
<code class="language-plaintext highlighter-rouge">send()</code> know whether his <code class="language-plaintext highlighter-rouge">send()</code> is the one that is exposed over the
NIC connection, or the serial connection?</p>

<p>The same component provides both. Therefore, CAmkES prefixes the
instances of functions in an Interface with the Interface-instance’s
name. In the dual-function NIC device’s case, it might have a
<code class="language-plaintext highlighter-rouge">provides &lt;INTERFACE_NAME&gt; serial</code> and a <code class="language-plaintext highlighter-rouge">provides &lt;INTERFACE_NAME&gt; nic</code>.
When a caller wants to call for the NIC-send, it would call,
nic_send(), and when a caller wants to invoke the Serial-send, it would
call, “serial_send()”.</p>

<p>So if the <code class="language-plaintext highlighter-rouge">Hello</code> interface is provided once by <code class="language-plaintext highlighter-rouge">Echo</code> as <code class="language-plaintext highlighter-rouge">a</code>, you would
call for the <code class="language-plaintext highlighter-rouge">a</code> instance of Echo’s <code class="language-plaintext highlighter-rouge">Hello</code> by calling for <code class="language-plaintext highlighter-rouge">a_hello()</code>.
But what if Echo had provided 2 instances of the <code class="language-plaintext highlighter-rouge">Hello</code> interface, and
the second one was named <code class="language-plaintext highlighter-rouge">a2</code>? Then in order to call on that second
<code class="language-plaintext highlighter-rouge">Hello</code> interface instance on Echo, you would call <code class="language-plaintext highlighter-rouge">a2_hello()</code>.</p>

<h2 id="exercises">Exercises</h2>

<h3 id="define-an-instance-in-the-composition-section-of-the-adl">Define an instance in the composition section of the ADL</h3>

<p><strong>Exercise</strong> First modify <code class="language-plaintext highlighter-rouge">hello-1.camkes</code>. Define instances of <code class="language-plaintext highlighter-rouge">Echo</code> and <code class="language-plaintext highlighter-rouge">Client</code> in the
<code class="language-plaintext highlighter-rouge">composition</code> section of the ADL.</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>assembly {
    composition {
         component EmptyComponent empty;
         // TODO define an Echo and a Client component
</code></pre></div></div>

<details>
  <summary><em>Quick solution</em></summary>

  <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>assembly {
    composition {
         component EmptyComponent empty;
         component Client client;
         component Echo echo;
</code></pre></div>  </div>
</details>

<h3 id="add-a-connection">Add a connection</h3>

<p><strong>Exercise</strong> Now add a connection from <code class="language-plaintext highlighter-rouge">client.hello</code> to <code class="language-plaintext highlighter-rouge">echo.hello</code>.</p>

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code>        <span class="cm">/* hint 1: use seL4RPCCall as the connector (or you could use seL4RPC if you prefer)
         * hint 2: look at
         * https://github.com/seL4/camkes-tool/blob/master/docs/index.md#creating-an-application
         */</span>
</code></pre></div></div>

<details>
  <summary><em>Quick solution</em></summary>

  <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code>        <span class="n">connection</span> <span class="n">seL4RPCCall</span> <span class="nf">hello_con</span><span class="p">(</span><span class="n">from</span> <span class="n">client</span><span class="p">.</span><span class="n">hello</span><span class="p">,</span> <span class="n">to</span> <span class="n">echo</span><span class="p">.</span><span class="n">hello</span><span class="p">);</span>
</code></pre></div>  </div>
</details>

<h3 id="define-an-interface">Define an interface</h3>

<p><strong>Exercise</strong> Define the interface for hello in <code class="language-plaintext highlighter-rouge">interfaces/HelloSimple.idl4</code>.</p>

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/* Simple RPC interface */</span>
<span class="n">procedure</span> <span class="n">HelloSimple</span> <span class="p">{</span>
    <span class="cm">/* TODO define RPC functions */</span>
    <span class="cm">/* hint 1: define at least one function that takes a string as input parameter. call it say_hello. no return value
     * hint 2: look at https://github.com/seL4/camkes-tool/blob/master/docs/index.md#creating-an-application
     */</span>
</code></pre></div></div>

<details>
  <summary><em>Quick solution</em></summary>

  <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    void say_hello(in string str);
</code></pre></div>  </div>
</details>

<h3 id="implement-a-rpc-function">Implement a RPC function</h3>
<p><strong>Exercise</strong> Implement the RPC hello function.</p>

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/* Implement the RPC function. */</span>
<span class="cm">/* hint 1: the name of the function to implement is a composition of an interface name and a function name:
 * i.e.: &lt;interface&gt;_&lt;function&gt;
 * hint 2: the interfaces available are defined by the component, e.g. in hello-1.camkes
 * hint 3: the function name is defined by the interface definition, e.g. in interfaces/HelloSimple.idl4
 * hint 4: so the function would be: hello_say_hello()
 * hint 5: the CAmkES 'string' type maps to 'const char *' in C
 * hint 6: make the function print out a mesage using printf
 * hint 7: look at https://github.com/seL4/camkes-tool/blob/master/docs/index.md#creating-an-application
 */</span>
</code></pre></div></div>

<details>
  <summary><em>Quick solution</em></summary>

  <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/* Implement the RPC function. */
void hello_say_hello(const char *str) {
    printf("Component %s saying: %s\n", get_instance_name(), str);
}
</code></pre></div>  </div>
</details>

<h3 id="invoke-a-rpc-function">Invoke a RPC function</h3>

<p><strong>Exercise</strong> Invoke the RPC function in <code class="language-plaintext highlighter-rouge">components/Client/src/client.c</code>.</p>

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    <span class="cm">/* TODO: invoke the RPC function */</span>
    <span class="cm">/* hint 1: the name of the function to invoke is a composition of an interface name and a function name:
     * i.e.: &lt;interface&gt;_&lt;function&gt;
     * hint 2: the interfaces available are defined by the component, e.g. in hello-1.camkes
     * hint 3: the function name is defined by the interface definition, e.g. in interfaces/HelloSimple.idl4
     * hint 4: so the function would be:  hello_say_hello()
     * hint 5: look at https://github.com/seL4/camkes-tool/blob/master/docs/index.md#creating-an-application
     */</span>
</code></pre></div></div>

<details>
  <summary><em>Quick solution</em></summary>

  <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    /* Invoke the RPC function */
    char *shello = "hello world";
    hello_say_hello(shello);
</code></pre></div>  </div>
</details>

<h2 id="done">Done</h2>

<p>Now build and run the project, if it compiles: Congratulations! Be sure to read up on the keywords and
structure of ADL: it’s key to understanding CAmkES. And well done on
writing your first CAmkES application.</p>



<p style="text-align: right;">

      Next: <a href="/Tutorials/hello-camkes-2">Events in CAmkES</a>
</p>

<hr>
    <p><em>Tutorial included from <a href="https://github.com/sel4/sel4-tutorials/blob/master/tutorials/hello-camkes-1/hello-camkes-1.md">github repo</a> <a href="https://github.com/sel4/sel4-tutorials/edit/master/tutorials/hello-camkes-1/hello-camkes-1.md">edit</a></em></p>
  </div>

  
    
<div class="sidebar-toc hidden-xs hidden-sm col-md-3 col-lg-3">
    <ul id="toc" class="section-nav">
<li class="toc-entry toc-h2"><a href="#prerequisites">Prerequisites</a></li>
<li class="toc-entry toc-h2"><a href="#initialising">Initialising</a></li>
<li class="toc-entry toc-h2"><a href="#background">Background</a>
<ul>
<li class="toc-entry toc-h3"><a href="#components">Components</a></li>
<li class="toc-entry toc-h3"><a href="#connections">Connections</a></li>
<li class="toc-entry toc-h3"><a href="#interfaces">Interfaces</a></li>
<li class="toc-entry toc-h3"><a href="#component-source">Component source</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#exercises">Exercises</a>
<ul>
<li class="toc-entry toc-h3"><a href="#define-an-instance-in-the-composition-section-of-the-adl">Define an instance in the composition section of the ADL</a></li>
<li class="toc-entry toc-h3"><a href="#add-a-connection">Add a connection</a></li>
<li class="toc-entry toc-h3"><a href="#define-an-interface">Define an interface</a></li>
<li class="toc-entry toc-h3"><a href="#implement-a-rpc-function">Implement a RPC function</a></li>
<li class="toc-entry toc-h3"><a href="#invoke-a-rpc-function">Invoke a RPC function</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#done">Done</a></li>
</ul>
</div>

  
</div>
<script src="/assets/js/toggle-markdown.js"></script>

    </main>
    


<footer class="site-footer">

  <h2 class="footer-heading">seL4 docs</h2>

  <div class="footer-col-wrapper">

    <div class="col-md-2">
      



<ul class="social-media-list">
  <li><a href="https://github.com/sel4"><i class="fab fa-github"></i> <span class="username">sel4</span></a></li><li><a href="https://github.com/sel4proj"><i class="fab fa-github"></i> <span class="username">sel4proj</span></a></li>
</ul>

    </div>

    <div class="col-md-8">
      <ul class="list-unstyled">
        <li>
          This site is for displaying seL4 related documentation.  Pull requests are welcome.
        </li>
        
          <li>
            Site last updated: Fri Feb 7 10:17:38 2025 +1100 ee78c8857c
          </li>
          <li>
                Page last updated: Mon Jan 6 18:52:01 2025 +1100 df31e5ccb8
          </li>
        
      </ul>
    </div>
    <div class="col-md-2">
<a href="https://github.com/seL4/docs/blob/master/Tutorials/hello-camkes-1.md">View page on GitHub</a>
      <br />
      <a href="https://github.com/seL4/docs/edit/master/Tutorials/hello-camkes-1.md">Edit page on GitHub</a>
      <br />
      <a href="/sitemap">Sitemap</a>
    </div>

  </div>

</footer>

  </body>
</html>
